Inside Macintosh: QuickDraw GX Objects /

Chapter 8 - Tag Objects / Using Tag Objects

Manipulating Tag Object Properties

This section describes how to manipulate the object properties of tag objects: tag type, contents, and owner count. To create and interact with tag objects as whole entities, use the functions described in the previous section, "Creating and Manipulating Tag Objects" beginning on page 8-7.

Getting and Setting a Tag Object's Tag Type and Contents

Fundamentally, tag objects are nothing but holders for whatever information or data that you want to attach to a QuickDraw GX object. If you want to access that information to inspect it or modify it, you can set up a buffer and call the GXGetTag function for a given tag object. GXGetTag places a copy of the tag object's information in your buffer, and it also returns the tag type of the tag object.

You can then modify the information in the buffer in any way you need to, and you can also change the tag type of the object, if desired. (Tag types that can be represented as four lowercase characters, such as 'abcd', are reserved by Apple Computer, Inc.) To return the modified contents or tag type to the tag object they came from, you then call the GXSetTag function.

Listing 8-2 is a library function that retrieves the data of the first tag object of a specified tag type or index attached to a given shape. If you specify an index and a buffer length to put the data in, the function returns the contents and tag type of the found tag. The function result is the number of tags found that fit the criteria you specify. The function uses the GXGetTag function to retrieve the tag object's contents.

Listing 8-2 Retrieving the contents of a tag object

long GetShapeUser(gxShape source, void *data, long *length, long 
requestedType, long *foundType, long index)
{
   if( index )       /* if index nonzero, get specific tag */
   {
      gxTag tempItem;

      if( GXGetShapeTags(source, requestedType, 
                           index, 1, &tempItem) )
      {
         long tempLength = GXGetTag(tempItem, foundType, data);
         if( length )
            *length = tempLength;
         return 1;                     /* no. of tags fund */
      }  else
      return 0;
   }
   else              /* otherwise just get tags of req. type */
      return GXGetShapeTags(source, requestedType, 
                              1, gxSelectToEnd, nil);
}

The GXGetTag function is described on page 8-18.

Using the GXGetTag and GXSetTag functions involves working with a copy of the tag object's contents in a buffer in application memory. You can also gain direct access to a tag object's contents (but not tag type) in QuickDraw GX memory, if desired. See the section "Directly Manipulating Tag Object Contents" beginning on page 8-11.

Manipulating a Tag Object's Owner Count

The owner count of an object indicates the number of current references to that object. In general, QuickDraw GX manages owner counts for you. For example, when you create a new tag object, QuickDraw GX sets the owner count of the new tag object to 1, which corresponds to the variable your application uses to reference the tag object. As another example, when you assign an existing tag object to a shape or transform (or any other object), QuickDraw GX increments the tag object's owner count, corresponding to the new reference to the tag object contained in the style or transform.

If you want to directly manage the owner count of a tag object yourself, or if you want to know whether a tag object is shared, you can

• use the function GXGetTagOwners to determine the current owner count
• use the function GXCloneTag to increment the owner count, whenever you create a new reference to the object
• use the function GXDisposeTag to decrement the owner count, deleting the tag object and freeing the memory used by it if the owner count goes to 0

The GXGetTagOwners function is described on page 8-20.

Note

In the chapter "Style Objects" in this book, the section on manipulating a style object's owner count discusses two common owner-count problems and how to avoid them. The problems are discussed in terms of style objects, but they apply equally well to tag objects. Refer to that discussion if you find that tag objects you create have owner counts that are higher or lower than you expect.